// /////////////////////////////////////////////////////////////////////////////
//
// Name:            IEventsContainer.java
// Author:          Michael Bartsch
//
// Desc :           Defines the IEventsContainer interface.
//
// License:         Copyright (C) 2009 Michael Bartsch
//
//                  This software is provided 'as-is', without any express or
//                  implied warranty. In no event will the authors be held
//                  liable for any damages arising from the use of this
//                  software.
//
//                  Permission is granted to anyone to use this software for
//                  any purpose, including commercial applications, and to
//                  alter it and redistribute it freely, subject to the
//                  following restrictions:
//
//                  1. The origin of this software must not be misrepresented;
//                  you must not claim that you wrote the original software. If
//                  you use this software in a product, an acknowledgment in the
//                  product documentation would be appreciated but is not
//                  required.
//
//                  2. Altered source versions must be plainly marked as such,
//                  and must not be misrepresented as being the original
//                  software.
//
//                  3. This notice may not be removed or altered from any source
//                  distribution.
//
// /////////////////////////////////////////////////////////////////////////////

// Package
package net.dotsimplicity.events;


// IEventsContainer interface
/**
 * Defines the methods an EventContainer should implement.
 * <p>
 * You can use this interface when you want to create your own EventContainer that ALSO requires
 * multiple inheritance. In all other cases you can simply extend {@link EventsContainer}.
 */
public interface IEventsContainer
{
	/**
	 * Adds the given {@link Event} to the container.
	 * @param event          Reference to the Event to add
	 */
	void addEvent(Event event);
	/**
	 * Adds the given {@link Event events} to the container.
	 * @param events         Reference to the Events to add
	 */
	void addEvents(Event [] events);
	
	/**
	 * Connects the method with the given name and the required parameters of the given object to
	 * the {@link Event} with the given name.
	 * @param eventName      Name of the Event
	 * @param object         Instance of the object
	 * @param methodName     Name of the method
	 */
	void connectEventSlot(String eventName, Object object, String methodName);
	/**
	 * Connects the static method with the given name and the required parameters of the given class
	 * to the {@link Event} with the given name.
	 * @param eventName      Name of the Event
	 * @param classReference Reference to the class
	 * @param methodName     Name of the method
	 */
	void connectEventSlot(String eventName, Class<?> classReference, String methodName);
	
	/**
	 * Create an {@link Event} with no parameters.
	 * @param eventName      Name of the Event
	 * @return The created Event if creation was successful, otherwise null.
	 */
	Event createEvent(String eventName);	
	/**
	 * Create an {@link Event} with the given parameter.
	 * @param eventName      Name of the Event
	 * @param parameter      Required parameter that subscribed EventSlots should implement
	 * @return The created Event if creation was successful, otherwise null.
	 */
	Event createEvent(String eventName, Class<?> parameter);
	/**
	 * Create an {@link Event} with the given parameters.
	 * @param eventName      Name of the Event
	 * @param parameters     Required parameters that subscribed EventSlots should implement
	 * @return The created Event if creation was successful, otherwise null.
	 */
	Event createEvent(String eventName, Class<?> [] parameters);
	/**
	 * Create several {@link Event Events} with no parameters.
	 * @param eventNames     Array of Event names
	 * @return Array of Events if creation of all Events was successful, otherwise null.
	 */
	Event [] createEvents(String [] eventNames);
	/**
	 * Create several {@link Event Events} with the given parameter.
	 * @param eventNames     Array of Event names
	 * @param parameter      Required parameter that subscribed EventSlots should implement
	 * @return Array of Events if creation of all Events was successful, otherwise null.
	 */
	Event [] createEvents(String [] eventNames, Class<?> parameter);
	/**
	 * Create several {@link Event Events} with the given parameter.
	 * @param eventNames     Array of Event names
	 * @param parameters     Required parameters that subscribed EventSlots should implement
	 * @return Array of Events if creation of all Events was successful, otherwise null.
	 */
	Event [] createEvents(String [] eventNames, Class<?> [] parameters);
	
	/**
	 * Disconnects the method with the given name of the given object from the {@link Event} 
	 * with the given name.
	 * @param eventName      Name of the Event
	 * @param object         Instance of the object
	 * @param methodName     Name of the method
	 */
	void disconnectEventSlot(String eventName, Object object, String methodName);
	/**
	 * Disconnects the static method with the given name of the given class from the {@link Event} 
	 * with the given name.
	 * @param eventName      Name of the Event
	  @param classReference Reference to the class
	 * @param methodName     Name of the method
	 */
	void disconnectEventSlot(String eventName, Class<?> classReference, String methodName);
	
	/**
	 * Emits a signal to the {@link Event} with the given name.
	 * @param eventName      Name of the Event
	 */
	void emitEventSignal(String eventName);
	/**
	 * Emits a signal to the {@link Event} with the given name and with the given argument.
	 * @param eventName      Name of the Event
	 * @param argument       Argument passed together with the signal
	 */
	void emitEventSignal(String eventName, Object argument);
	/**
	 * Emits a signal to the {@link Event} with the given name and the given arguments.
	 * @param eventName      Name of the Event
	 * @param arguments      Arguments passed together with the signal
	 */
	void emitEventSignal(String eventName, Object [] arguments);
	
	/**
	 * Returns the {@link Event} with the given name. 
	 * @return Reference to Event if found, otherwise null.
	 */
	Event getEvent(String eventName);
	
	/**
	 * Remove all {@link Event Events} from this EventsContainer.
	 */
	void removeAllEvents();
	/**
	 * Removes the given {@link Event} from this EventsContainer.
	 * @param event          Reference to the Event that has to be removed
	 */
	void removeEvent(Event event);
	/**
	 * Removes the {@link Event} with the given name.
	 * @param eventName      Name of the Event
	 */
	void removeEvent(String eventName);
	/**
	 * Removes the given {@link Event Events} from this EventsContainer.
	 * @param events         Array of Events that have to be removed
	 */
	void removeEvents(Event [] events);
	/**
	 * Removes the {@link Event Events} with the given names.
	 * @param eventNames     Array of Event names
	 */
	void removeEvents(String [] eventNames);
}

// End of File